NXT system commands
In this section we've got:
Contents
- NXT_SetBrickName
- NXT_SendKeepAlive
- NXT_GetBatteryLevel
All functions beginning with NXT_ are basically just ported from the official LEGO NXT Bluetooth Protocol and Direct Commands documentation.
Specify a name up to 15 chars long (preferrably no spaces) to name your brick. This can be read out by bluetooth adapters (and later on in a MATLAB function as well, NXT_GetDeviceInfo, once it will be implemented). This name will also show up in your bluetooth adapter software when browsing for devices.
NXT_SetBrickName('RaceRobotV3');
To keep the NXT from turning off automatically, send a keep-alive packet from time to time (if needed):
NXT_SendKeepAlive('dontreply');
If you're interested in the internal sleep time limit setting, just request it:
[status SleepTimeLimit] = NXT_SendKeepAlive('reply'); % To see after how many minutes the NXT will shut down: minutes = SleepTimeLimit / 1000 / 60;
So how much energy does my bot have left?
voltage = NXT_GetBatteryLevel; % actually, the unit is milli volts, so voltage = voltage / 1000; % :-)
Every function that retrieves (i.e. "gets") values from the NXT is internally split into two parts. But this doesn't have to concern you right now. Note how we called the functions without passing a blutooth handle - we simply set the default handle at the beginning of our program or session.
NXT direct commands
These are the interesting ones:
- NXT_PlayTone
- NXT_SetInputMode
- NXT_ResetInputScaledValue
- NXT_GetInputValues
- NXT_ResetMotorPosition
- NXT_SetOutputState
- NXT_GetOutputState
- NXT_StartProgram, NXT_StopProgram
- NXT_LSWrite, NXT_LSGetStatus, NXT_LSRead
This section only covers the syntax, for details what the functions do please consider the official LEGO documentation or the function help.
% frequency is in Hz, duration in ms
NXT_PlayTone(frequency, duration);
% the common way would be this NXT_SetInputMode(InputPort, SensorTypeDesc, SensorModeDesc, 'dontreply'); % but if you want an acknowledgement (usually not needed), then use status = NXT_SetInputMode(InputPort, SensorTypeDesc, SensorModeDesc, 'reply'); % note: the statusbyte will be automatically checked anyway (and a warning % issued if necessary), but you can still check the status now to handle the % consequences properly...
NXT_ResetInputScaledValue(port);
% in this function there is no way to request an acknowledgement...
% only call this after you've set a proper input mode data = NXT_GetInputValues(port); % simple function, heavy output: out.Port % from what port out.Valid % is this sensorreading valid? if not, well... discard? out.Calibrated % for future use of NXT firmware out.TypeByte % sensor type out.TypeName % sensor type, but human readable out.ModeByte % sensor mode out.ModeName % sensor mode, human readable out.RawADVal % raw digital value, do nut use out.NormalizedADVal % use THIS, normalized value, 10bits, between 0 and 1023 out.ScaledVal % use this, depends on the input mode you set out.CalibratedVal % for future use of NXT firmware
% Notation as seen in the Direct Commands doc: % true = relative = BlockTachoCount, false = absolute = RotationCount NXT_ResetMotorPosition(port, true);
% more lines for better readability NXT_SetOutputState(whatmotor, ... % port 20, ... % power true, ... % motoron? true, ... % brake? 'SPEED', ... % regulation 0, ... % turnratio 'RUNNING', ... % runstate 0, ... % tacho limit (0 = forever) 'dontreply'); % replymode
out = NXT_GetOutputState(port); % just like with GetInputValues: simple call, complex output: out.Port % motornumber out.Power % power out.Mode % complete mode-byte (bitfield), see below for easier usage out.ModeIsMOTORON % boolean, state of MOTORON bit (false means motor has no power) out.ModeIsBRAKE % boolean, state of electronic braking (improves motor performance) out.ModeIsREGULATED % boolean, if set, see RegModeName, if not set, reg mode will be IDLE out.RegModeByte % regulation mode, binary out.RegModeName % name of regulation mode: IDLE, SPEED, or SYNC out.TurnRatio % turn ratio, 0 = straight forward out.RunStateByte % run state, binary out.RunStateName % name of run state: IDLE, RUNNING, RAMPUP or RAMPDOWN out.TachoLimit % current tacho limit (we'll call it AngleLimit later on) out.TachoCount % TachoCount = internal cumulative motor-degree-counter. out.BlockTachoCount % motor-degree-counter, resettable using "ResetMotorPosition relative" out.RotationCount % motor-degree-counter, resettable using "ResetMotorPosition absolute"
To execute "real" Mindstorms programs on the NXT (i.e. programs that you created using the official LEGO software and stored it locally on the NXT), you can call this function:
NXT_StartProgram('MyDemo.rxe'); % the file extension '.rxe' can be omitted, it will then be automatically added
Stopping the currently running program can be accomplished with
NXT_StopProgram();
There are three more NXT direct commands: NXT_LSGetStatus, NXT_LSWrite, NXT_LSRead. They all have one purpose: Address digital sensors that use the I²C-Protocol. An example is the ultrasonic sensor, and for more documentation you might want to see the sourcecode of OpenUltrasonic and GetUltrasonic.
The idea is to send data (containing I²C payload) first with NXT_LSWrite. Then check the sensor status in a loop using NXT_LSGetStatus until it is ready, i.e. until the status byte reports no error and all requested bytes are available. Those bytes can then be received using NXT_LSRead.